/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.commons.configuration.event;

import java.util.EventObject;

/**
 * <p>
 * An event class for reporting updates on a configuration object.
 * </p>
 * <p>
 * Event objects of this type are used for "raw" events, i.e.
 * unfiltered modifications of any kind. A level with semantically higher events
 * (e.g. for property changes) may be built on top of this fundamental event
 * mechanism.
 * </p>
 * <p>
 * Each event can contain the following data:
 * <ul>
 * <li>A source object, which is usually the configuration object that was
 * modified.</li>
 * <li>The event's type. This is a numeric value that corresponds to constant
 * declarations in concrete configuration classes. It describes what exactly has
 * happended.</li>
 * <li>If available, the name of the property whose modification caused the
 * event.</li>
 * <li>If available, the value of the property that caused this event.</li>
 * <li>A flag whether this event was generated before or after the update of
 * the source configuration. A modification of a configuration typically causes
 * two events: one event before and one event after the modification is
 * performed. This allows event listeners to react at the correct point of time.</li>
 * </ul>
 * </p>
 * <p>
 * The following standard events are generated by typical configuration
 * implementations (the constants for the event types are defined in
 * <code>{@link org.apache.commons.configuration.AbstractConfiguration}</code>):
 * <dl>
 * <dt>EVENT_ADD_PROPERTY</dt>
 * <dd>This event is triggered for each call of the <code>addProperty()</code>
 * method of a configuration object. It contains the name of the property, to
 * which new data is added, and the value object that is added to this property
 * (this may be an array or a list if multiple values are added).</dd>
 * <dt>EVENT_SET_PROPERTY</dt>
 * <dd>Calling the <code>setProperty()</code> method triggers this event. The
 * event object stores the name of the affected property and its new value.</dd>
 * <dt>EVENT_CLEAR_PROPERTY</dt>
 * <dd>If a property is removed from a configuration (by calling the
 * <code>clearProperty()</code> method), an event of this type is fired. In
 * this case the event object only stores the name of the removed property, the
 * value is <b>null</b>.</dd>
 * <dt>EVENT_CLEAR</dt>
 * <dd>This event is fired when the whole configuration is cleared. The
 * corresponding event object contains no additional data.</dd>
 * </dl>
 * </p>
 *
 * @author <a
 * href="http://commons.apache.org/configuration/team-list.html">Commons
 * Configuration team</a>
 * @version $Id: ConfigurationEvent.java 561230 2007-07-31 04:17:09Z rahul $
 * @since 1.3
 */
public class ConfigurationEvent extends EventObject
{
    /**
     * The serial version UID.
     */
    private static final long serialVersionUID = 3277238219073504136L;

    /** Stores the event type. */
    private int type;

    /** Stores the property name. */
    private String propertyName;

    /** Stores the property value. */
    private Object propertyValue;

    /** Stores the before update flag. */
    private boolean beforeUpdate;

    /**
     * Creates a new instance of <code>ConfigurationEvent</code> and
     * initializes it.
     *
     * @param source the event source
     * @param type the event's type
     * @param propertyName the name of the affected property
     * @param propertyValue the value of the affected property
     * @param beforeUpdate the before update flag
     */
    public ConfigurationEvent(Object source, int type, String propertyName,
            Object propertyValue, boolean beforeUpdate)
    {
        super(source);
        this.type = type;
        this.propertyName = propertyName;
        this.propertyValue = propertyValue;
        this.beforeUpdate = beforeUpdate;
    }

    /**
     * Returns the name of the affected property. This can be <b>null</b> if no
     * property change has lead to this event.
     *
     * @return the name of the property
     */
    public String getPropertyName()
    {
        return propertyName;
    }

    /**
     * Returns the value of the affected property if available.
     *
     * @return the value of the property; can be <b>null</b>
     */
    public Object getPropertyValue()
    {
        return propertyValue;
    }

    /**
     * Returns the type of this event. This describes the update process that
     * caused this event.
     *
     * @return the event's type
     */
    public int getType()
    {
        return type;
    }

    /**
     * Returns a flag if this event was generated before or after an update.
     *
     * @return <b>true</b> if this event was generated before an update;
     * <b>false</b> otherwise
     */
    public boolean isBeforeUpdate()
    {
        return beforeUpdate;
    }
}